package com.m1.tzolkin.model.util;

import java.io.Serializable;
import java.util.Set;

/**
 * Un mod�le de stock d'�l�ments d'un m�me type.
 * Un stock est un ensemble de valeurs associ�es � des �l�ments.
 *  
 * @inv <pre>
 *     contains(m) si cette somme contient au sens large m. </pre>
 *     
 * @cons <pre>
 * $DESC$
 *     Une somme remplie des valeurs de s.
 * $ARGS$
 *     Sum<E> s
 * $PRE$
 *     s != null
 * $POST$
 *     equals(s) </pre>
 *
 */
public interface IStock<E extends IResource> extends Serializable {

	// REQUETES
	
	/**
	 * Retourne la quantit� de r que ce stock contient.
	 * @pre <pre>
	 *     r != null </pre>
	 */
	int get(E r);
	
	/**
	 * Retourne true si ce stock contient m.
	 * @pre <pre>
	 *     m != null </pre>
	 */
	boolean contains(IStock<E> m);

	/**
	 * Retourne true si ce stock contient m
	 *  � 1 unit� de r pr�s.
	 * @pre <pre>
	 *     m != null
	 *     r != null </pre>
	 */
	boolean contains(IStock<E> m, E r);
	
	/**
	 * Retourne les cl�s de ce stock.
	 */
	Set<E> keySet();
	
	/**
	 * Retourne true si s est �quivalente � ce stock.
	 */
	boolean equals(IStock<E> s);
	
	/**
	 * Retourne la quantit� totale contenue dans ce stock.
	 */
	int getTotal();
	
	// COMMANDES
	
	/**
	 * Ajoute une unit� de l'�l�ment r.
	 * @pre <pre>
	 *     r != null </pre>
	 */
	IStock<E> add(E r);
	
	/**
	 * Retire une unit� de l'�l�ment r.
	 * @pre <pre>
	 *     r != null </pre>
	 */
	IStock<E> remove(E r);
	
	/**
	 * Ajoute i unit�s de l'�l�ment r.
	 * @pre <pre>
	 *     r != null
	 *     i >= 0 </pre>
	 */
	IStock<E> add(E r, int i);
	
	/**
	 * Retire i unit�s de l'�l�ment r.
	 * @pre <pre>
	 *     r != null
	 *     i >= 0 </pre>
	 */
	IStock<E> remove(E r, int i);
	
	/**
	 * Ajoute le stock s � ce stock.
	 * @pre <pre>
	 *     s != null </pre>
	 */
	IStock<E> add(IStock<E> s);
	
	/**
	 * Retire le stock s � ce stock.
	 * @pre <pre>
	 *     s != null </pre>
	 */
	IStock<E> remove(IStock<E> s);
	
}
